Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

Creating Web Service Clients with JAX-RPC

This section shows how to create and run four types of clients:

When you run these client examples, they will access the MyHelloService that you deployed in the preceding section.

Static Stub Client Example

This example resides in the <INSTALL>/j2eetutorial14/examples/jaxrpc/staticstub directory.

HelloClient is a stand-alone program that calls the sayHello method of the MyHelloService. It makes this call through a stub, a local object which acts as a proxy for the remote service. Because the stub is created before runtime (by wscompile), it is usually called a static stub.

Coding the Static Stub Client

Before it can invoke the remote methods on the stub the client performs these steps:

  1. Creates a Stub object:
  2. (Stub)(new MyHelloService_Impl().getHelloIFPort())

    The code in this method is implementation-specific because it relies on a MyHelloService_Impl object, which is not defined in the specifications. The MyHelloService_Impl class will be generated by wscompile in the following section.

  3. Sets the endpoint address that the stub uses to access the service:
  4. stub._setProperty
    (javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, args[0]);

    At runtime, the endpoint address is passed to HelloClient in args[0] as a command-line parameter, which asant gets from the endpoint.address property in the build.properties file. This address must match the one you set for the service in Specifying the Endpoint Address.

  5. Casts stub to the service endpoint interface, HelloIF:
  6. HelloIF hello = (HelloIF)stub;

Here is the full source code listing for the HelloClient.java file, which is located in the <INSTALL>/j2eetutorial14/examples/jaxrpc/staticstub/src/ directory:

package staticstub;

import javax.xml.rpc.Stub;

public class HelloClient {

    private String endpointAddress;

    public static void main(String[] args) {

        System.out.println("Endpoint address = " + args[0]);
        try {
            Stub stub = createProxy();
            stub._setProperty
              (javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY,
               args[0]); 
            HelloIF hello = (HelloIF)stub;
            System.out.println(hello.sayHello("Duke!"));
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }    

    private static Stub createProxy() {
        // Note: MyHelloService_Impl is implementation-specific.
        return 
        (Stub) (new MyHelloService_Impl().getHelloIFPort());
    }
} 

Building and Running the Static Stub Client

Before performing the steps in this section, you must first create and deploy MyHelloService as described in Creating a Web Service with JAX-RPC.

To build and package the client, go to the <INSTALL>/j2eetutorial14/examples/jaxrpc/staticstub/ directory and type the following:

asant build 

The preceding command invokes three asant tasks:

The generate-stubs task runs the wscompile tool as follows:

wscompile -gen:client -d build/client -classpath build/server 
config-wsdl.xml 

This wscompile command reads the MyHelloService.wsdl file that was generated in Building the Service. The wscompile command generates files based on the information in the WSDL file and on the command-line flags. The -gen:client flag instructs wscompile to generate the stubs and other runtime files. The -d flag tells the tool to write the output to the build/client subdirectory. The tool reads the following config-wsdl.xml file, which specifies the location of the WSDL file:

<?xml version="1.0" encoding="UTF-8"?>
<configuration 
   xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">
  <wsdl location="build/MyHelloService.wsdl"
       packageName="staticstub"/>
</configuration> 

The compile-client task compiles src/HelloClient.java and writes the class file to the build subdirectory.

The package-client task packages the files created by the generate-stubs and compile-client tasks into the dist/client.jar file. Except for the HelloClient.class, all of the files in client.jar were created by wscompile. Note that wscompile generated the HelloIF.class based on the information it read from the MyHelloService.wsdl file.

To run the client, type the following:

asant run 

The client should display the following line:

Hello Duke! 

Dynamic Proxy Client Example

This example resides in the <INSTALL>/j2eetutorial14/examples/jaxrpc/dynamicproxy/ directory.

The client in the preceding section used a static stub for the proxy. In contrast, the client example in this section calls a remote procedure through a dynamic proxy, a class that is created during runtime. Although the source code for the static stub client relied on an implementation-specific class, the code for the dynamic proxy client does not have this limitation.

Coding the Dynamic Proxy Client

The DynamicProxyHello program constructs the dynamic proxy as follows:

  1. Creates a Service object named helloService:
  2. Service helloService =
    serviceFactory.createService(helloWsdlUrl,
    new QName(nameSpaceUri, serviceName));

    A Service object is a factory for proxies. To create the Service object (helloService), the program calls the createService method on another type of factory, a ServiceFactory object.

    The createService method has two parameters, the URL of the WSDL file and a QName object. At runtime, the client gets information about the service by looking up its WSDL. In this example, the URL of the WSDL file points to the WSDL that was deployed with MyHelloService:

    http://localhost:1024/jaxrpc-hello/hello?WSDL

    A QName object is a tuple that represents an XML qualified name. The tuple is composed of a namespace URI and the local part of the qualified name. In the QName parameter of the createService invocation, the local part is the service name, MyHelloService.

  3. The program creates a proxy (myProxy) with a type of the service endpoint interface (HelloIF):
  4. dynamicproxy.HelloIF myProxy =
    (dynamicproxy.HelloIF)helloService.getPort(
    new QName(nameSpaceUri, portName),
    dynamicproxy.HelloIF.class);

    The helloService object is a factory for dynamic proxies. To create myProxy, the program calls the getPort method of helloService. This method has two parameters: a QName object that specifies the port name and a java.lang.Class object for the service endpoint interface. The port name, HelloIFPort, is also specified by the WSDL file.

Here is the listing for the HelloClient.java file, located in the <INSTALL>/j2eetutorial14/examples/jaxrpc/dynamicproxy/src/ directory:

package dynamicproxy;

import java.net.URL;
import javax.xml.rpc.Service;
import javax.xml.rpc.JAXRPCException;
import javax.xml.namespace.QName;
import javax.xml.rpc.ServiceFactory;
import dynamicproxy.HelloIF;

public class HelloClient {

    public static void main(String[] args) {
        try {

            String UrlString = args[0] + "?WSDL";
            String nameSpaceUri = "urn:Foo";
            String serviceName = "MyHelloService";
            String portName = "HelloIFPort";

            System.out.println("UrlString = " + UrlString);
            URL helloWsdlUrl = new URL(UrlString);
            
            ServiceFactory serviceFactory =
                ServiceFactory.newInstance();
            
            Service helloService =
                serviceFactory.createService(helloWsdlUrl, 
                new QName(nameSpaceUri, serviceName));
            
            dynamicproxy.HelloIF myProxy = 
                (dynamicproxy.HelloIF) 
                helloService.getPort(
                new QName(nameSpaceUri, portName), 
                dynamicproxy.HelloIF.class); 

            System.out.println(myProxy.sayHello("Buzz"));

        } catch (Exception ex) {
            ex.printStackTrace();
        } 
    } 
}  

Building and Running the Dynamic Proxy Client

Before performing the steps in this section, you must first create and deploy MyHelloService as described in Creating a Web Service with JAX-RPC.

To build and package the client, go to the <INSTALL>/j2eetutorial14/examples/jaxrpc/dynamicproxy/ directory and type the following:

asant build 

The preceding command runs these tasks:

The generate-stubs task runs wscompile, which reads the MyHelloService.wsdl file and generates the service endpoint interface class (HelloIF.class). Although this wscompile invocation also creates stubs, the dynamic proxy client does not use these stubs, which are required only by static stub clients. For more information about the wscompile command that is run by generate-stubs, see Building and Running the Static Stub Client.

The compile-client task compiles the src/HelloClient.java file.

The package-proxy task creates the dist/client.jar file, which contains HelloIF.class and HelloClient.class.

To run the client, type the following:

asant run 

The client should display the following line:

Hello Buzz! 

Dynamic Invocation Interface (DII) Client Example

This example resides in the <INSTALL>/j2eetutorial14/examples/jaxrpc/dii directory.

With the dynamic invocation interface (DII), a client can call a remote procedure even if the signature of the remote procedure or the name of the service are unknown until runtime. In contrast to a static stub or dynamic proxy client, a DII client does not require runtime classes generated by wscompile. However, as you'll see in the following section, the source code for a DII client is more complicated than the code of the other two types of clients.

This example is for advanced users who are familiar with WSDL documents. (See Further Information.)

Coding the DII Client

The DIIHello program performs these steps:

  1. Creates a Service object.
  2. Service service =
    factory.createService(new QName(qnameService));

    To get a Service object, the program invokes the createService method of a ServiceFactory object. The parameter of the createService method is a QName object that represents the name of the service, MyHelloService. The WSDL file specifies this name as follows:

    <service name="MyHelloService">

  3. From the Service object, creates a Call object:
  4. QName port = new QName(qnamePort);
    Call call = service.createCall(port);

    A Call object supports the dynamic invocation of the remote procedures of a service. To get a Call object, the program invokes the Service object's createCall method. The parameter of createCall is a QName object that represents the service endpoint interface, MyHelloServiceRPC. In the WSDL file, the name of this interface is designated by the portType element:

    <portType name="HelloIF">

  5. Sets the service endpoint address on the Call object:
  6. call.setTargetEndpointAddress(endpoint);

    In the WSDL file, this address is specified by the <soap:address> element.

  7. Sets these properties on the Call object:
  8. SOAPACTION_USE_PROPERTY
    SOAPACTION_URI_PROPERTY
    ENCODING_STYLE_PROPERTY

    To learn more about these properties, refer to the SOAP and WSDL documents listed in Further Information.

  9. Specifies the method's return type, name, and parameter:
  10. QName QNAME_TYPE_STRING = new QName(NS_XSD, "string");
    call.setReturnType(QNAME_TYPE_STRING);

    call.setOperationName(new QName(BODY_NAMESPACE_VALUE,
    "sayHello"));

    call.addParameter("String_1", QNAME_TYPE_STRING,
    ParameterMode.IN);

    To specify the return type, the program invokes the setReturnType method on the Call object. The parameter of setReturnType is a QName object that represents an XML string type.

    The program designates the method name by invoking the setOperationName method with a QName object that represents sayHello.

    To indicate the method parameter, the program invokes the addParameter method on the Call object. The addParameter method has three arguments: a String for the parameter name (String_1), a QName object for the XML type, and a ParameterMode object to indicate the passing mode of the parameter (IN).

  11. Invokes the remote method on the Call object:
  12. String[] params = { "Murphy" };
    String result = (String)call.invoke(params);

    The program assigns the parameter value (Murphy) to a String array (params) and then executes the invoke method with the String array as an argument.

Here is the listing for the HelloClient.java file, located in the <INSTALL>/j2eetutorial14/examples/jaxrpc/dii/src/ directory:

package dii;

import javax.xml.rpc.Call;
import javax.xml.rpc.Service;
import javax.xml.rpc.JAXRPCException;
import javax.xml.namespace.QName;
import javax.xml.rpc.ServiceFactory;
import javax.xml.rpc.ParameterMode;

public class HelloClient {

    private static String qnameService = "MyHelloService";
    private static String qnamePort = "HelloIF";

    private static String BODY_NAMESPACE_VALUE = 
        "urn:Foo";
    private static String ENCODING_STYLE_PROPERTY =
         "javax.xml.rpc.encodingstyle.namespace.uri"; 
    private static String NS_XSD = 
        "http://www.w3.org/2001/XMLSchema";
    private static String URI_ENCODING =
         "http://schemas.xmlsoap.org/soap/encoding/";

    public static void main(String[] args) {

        System.out.println("Endpoint address = " + args[0]);

        try {
            ServiceFactory factory = 
                ServiceFactory.newInstance();
            Service service = 
                factory.createService(
                new QName(qnameService));
    
            QName port = new QName(qnamePort);
    
            Call call = service.createCall(port);
            call.setTargetEndpointAddress(args[0]);
    
            call.setProperty(Call.SOAPACTION_USE_PROPERTY, 
                new Boolean(true));
            call.setProperty(Call.SOAPACTION_URI_PROPERTY
                 "");
            call.setProperty(ENCODING_STYLE_PROPERTY,
                URI_ENCODING);
            QName QNAME_TYPE_STRING = 
                        new QName(NS_XSD, "string");
            call.setReturnType(QNAME_TYPE_STRING);

            call.setOperationName(
                new QName(BODY_NAMESPACE_VALUE,"sayHello"));
            call.addParameter("String_1", QNAME_TYPE_STRING, 
                ParameterMode.IN);
            String[] params = { "Murph!" };

            String result = (String)call.invoke(params);
            System.out.println(result);

        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }
} 

Building and Running the DII Client

Before performing the steps in this section, you must first create and deploy MyHelloService as described in Creating a Web Service with JAX-RPC.

To build and package the client, go to the <INSTALL>/j2eetutorial14/examples/jaxrpc/dii/ directory and type the following:

asant build 

This build task compiles HelloClient and packages it into the dist/client.jar file. Unlike the previous client examples, the DII client does not require files generated by wscompile.

To run the client, type this command:

asant run 

The client should display this line:

Hello Murph! 

J2EE Application Client Example

Unlike the stand-alone clients in the preceding sections, the client in this section is a J2EE application client. Because it's a J2EE component, a J2EE applicatino client can locate a local Web service by invoking the JNDI lookup method.

J2EE Application HelloClient Listing

Here is the listing for the HelloClient.java file, located in the <INSTALL>/j2eetutorial14/examples/jaxrpc/appclient/src/ directory:

package appclient;

import javax.xml.rpc.Stub;
import javax.naming.*;

public class HelloClient {

    private String endpointAddress;

    public static void main(String[] args) {

        System.out.println("Endpoint address = " + args[0]);

        try {
            Context ic = new InitialContext();
            MyHelloService myHelloService = (MyHelloService) 
                ic.lookup("java:comp/env/service/MyJAXRPCHello");
            appclient.HelloIF helloPort = 
                myHelloService.getHelloIFPort();
            ((Stub)helloPort)._setProperty
                (Stub.ENDPOINT_ADDRESS_PROPERTY,args[0]);

            System.out.println(helloPort.sayHello("Jake!"));
            System.exit(0);

        } catch (Exception ex) {
            ex.printStackTrace();
            System.exit(1);
        }
    } 
} 

Building the J2EE Application Client

In a terminal window, go to the <INSTALL>/j2eetutorial14/examples/jaxrpc/appclient directory and type the following:

asant build 

The preceding command compiles HelloClient.java and runs wscompile by invoking the generate-mapping target. For more information on this target, see the section generate-mapping.

Packaging the J2EE Application Client

Packaging this client is a two-step process:

  1. Create an EAR file for a J2EE application.
  2. Create a JAR file for the application client and add it to the EAR file.

To create the EAR file, follow these steps:

  1. In deploytool, select FileRight ArrowNewRight ArrowApplication EAR.
  2. Click Browse.
  3. In the file chooser, navigate to <INSTALL>/j2eetutorial14/examples/jaxrpc/appclient.
  4. In the File Name field, enter HelloServiceApp.ear.
  5. Click New Application.
  6. Click OK.

To start the New Application Client wizard, select FileRight ArrowNewRight ArrowApplication Client JAR. The wizard displays the following dialog boxes.

  1. Introduction dialog box
    1. Read the explanatory text for an overview of the wizard's features.
    2. Click Next.
  2. JAR File Contents dialog box
    1. Select the button labelled Create New AppClient Module in Application.
    2. In the combo box below this button, select HelloServiceApp.
    3. In the AppClient Display Name field, enter HelloClient.
    4. Click Edit.
    5. In the tree under Available Files, locate the <INSTALL>/examples/jaxrpc/appclient directory.
    6. Select the build directory.
    7. Click Add.
    8. Click OK.
    9. Click Next.
  3. General dialog box
    1. In the Main Class combo box, select appclient.HelloClient.
    2. Click Next.
    3. Click Finish.

Specifying the Web Reference

When it invokes the lookup method, the HelloClient refers to the Web service as follows:

MyHelloService myHelloService = (MyHelloService)
ic.lookup("java:comp/env/service/MyJAXRPCHello"); 

You specify this reference as follows.

  1. In the tree, select HelloClient.
  2. Select the Web Service Refs tab.
  3. Click Add.
  4. In the Coded Name field, enter service/MyJAXRPCHello.
  5. In the Service Interface combo box, select appclient.MyHelloService.
  6. In the WSDL File combo box, select MyHelloService.wsdl.
  7. In the Namespace field, enter urn:Foo.
  8. In the Local Part field, enter MyHelloService.
  9. In the Mapping File combo box, select mapping.xml.
  10. Click OK.

Deploying and Running the J2EE Application Client

Before performing the steps in this section, you must first create and deploy the MyHelloService as described in Creating a Web Service with JAX-RPC.

To deploy the J2EE application client, follow these steps:

  1. Select the HelloServiceApp application.
  2. Select ToolsRight ArrowDeploy.
  3. In the Deploy Module dialog select the checkbox labelled Return Client JAR.
  4. In the field below the checkbox, enter this directory:
  5. <INSTALL>/j2eetutorial14/examples/jaxrpc/appclient 
    
  6. Click OK.

To run the client:

  1. In a terminal window, go to the <INSTALL>/j2eetutorial14/examples/jaxrpc/appclient/ directory.
  2. Type the following on a single line:
  3. appclient -client HelloServiceAppClient.jar
    http://localhost:1024/hello-jaxrpc/hello 
    

The client should display this line:

Hello Jake! 

Other JAX-RPC Client Examples

Chapter 15 shows how a JSP page can be a static stub client that accesses a remote Web service. See the section, The Example JSP Pages.

Divider
Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

All of the material in The J2EE 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.